﻿<!DOCTYPE HTML>
<html lang="zh">
<head>
<title>ImageSearch - 语法 &amp; 使用 | AutoHotkey v2</title>
<meta name="description" content="The ImageSearch function searches a region of the screen for an image." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<script type="text/javascript">$(function(){0<=window.navigator.userAgent.toLowerCase().indexOf("ucbrowser")&&CaoNiMaDeUc()})</script>
</head>
<body>

<h1>ImageSearch</h1>

<p>Searches a region of the screen for an image.</p>

<pre class="Syntax"><span class="func">ImageSearch</span> OutputVarX, OutputVarY, X1, Y1, X2, Y2, ImageFile</pre>
<h2 id="Parameters">参数</h2>
<dl>

  <dt>OutputVarX/Y</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#variables">变量</a></p>
    <p>The names of the variables in which to store the X and Y coordinates of the upper-left pixel of where the image was found on the screen (if no match is found, the variables are made blank). Coordinates are relative to the active window unless <a href="CoordMode.htm">CoordMode</a> was used to change that.</p>
  </dd>

  <dt>X1,Y1</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>The X and Y coordinates of the upper left corner of the rectangle to search. <strong>Coordinates are relative to the active window unless <a href="CoordMode.htm">CoordMode</a> was used to change that.</strong></p>
  </dd>

  <dt>X2,Y2</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>The X and Y coordinates of the lower right corner of the rectangle to search. Coordinates are relative to the active window unless <a href="CoordMode.htm">CoordMode</a> was used to change that.</p>
  </dd>

  <dt>ImageFile</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>The file name of an image, which is assumed to be in <a href="../Variables.htm#WorkingDir">A_WorkingDir</a> if an absolute path isn't specified. Supported image formats include ANI, BMP, CUR, EMF, Exif, GIF, ICO, JPG, PNG, TIF, and WMF (BMP images must be 16-bit or higher). Other sources of icons include the following types of files: EXE, DLL, CPL, SCR, and other types that contain icon resources.</p>
      <p><strong>Options</strong>: Zero or more of the following strings may be also be present immediately before the name of the file. Separate each option from the next with a single space or tab. 例如: <code>"*2 *w100 *h-1 C:\Main Logo.bmp"</code>.</p>
      <p><strong>*IconN</strong>: To use an icon group other than the first one in the file, specify <code>*Icon</code> followed immediately by the number of the group. 例如, <code>*Icon2</code> would load the default icon from the second icon group.</p>    
    <p><strong>*n</strong> (variation): Specify for <strong>n</strong> a number between 0 and 255 (inclusive) to indicate the allowed number of shades of variation in either direction for the intensity of the red, green, and blue components of each pixel's color. 例如, <code>*2</code> would allow two shades of variation. This parameter is helpful if the coloring of the image varies slightly or if <em>ImageFile</em> uses a format such as GIF or JPG that does not accurately represent an image on the screen. If you specify 255 shades of variation, all colors will match. The default is 0 shades.</p>
    <p><strong>*TransN</strong>: This option makes it easier to find a match by specifying one color within the image that will match any color on the screen. It is most commonly used to find PNG, GIF, and TIF files that have some transparent areas (however, icons do not need this option because their transparency is automatically supported). For GIF files, <code>*TransWhite</code> might be most likely to work. For PNG and TIF files, <code>*TransBlack</code> might be best. Otherwise, specify for <strong>N</strong> some other color name or RGB value (see the <a href="../misc/Colors.htm">color chart</a> for guidance, or use <a href="PixelGetColor.htm">PixelGetColor</a> in its RGB mode). Examples: <code>*TransBlack</code>, <code>*TransFFFFAA</code>, <code>*Trans0xFFFFAA</code>.</p>    
    <p><strong>*wn</strong> and <strong>*hn</strong>: Width and height to which to scale the image (this width and height also determines which icon to load from a multi-icon .ICO file). If both these options are omitted, icons loaded from ICO, DLL, or EXE files are scaled to the system's default small-icon size, which is usually 16 by 16 (you can force the actual/internal size to be used by specifying <code>*w0 *h0</code>). Images that are not icons are loaded at their actual size. To shrink or enlarge the image while preserving its aspect ratio, specify -1 for one of the dimensions and a positive number for the other. 例如, specifying <code>*w200 *h-1</code> would make the image 200 pixels wide and cause its height to be set automatically.</p>
    <p>A <a href="../misc/ImageHandles.htm">bitmap or icon handle</a> can be used instead of a filename. 例如, <code>"HBITMAP:*" handle</code>.</p>
  </dd>

</dl>

<h2 id="Return_Value">返回值</h2>
<p>类型: <a href="../Concepts.htm#boolean">整数(布尔值)</a></p>
<p>This function returns 1 (true) if the image was found in the specified region, or 0 (false) if it was not found.</p>

<h2 id="Error_Handling">错误处理</h2>
<p>An exception is thrown if an invalid parameter was detected or the image could not be loaded.</p>

<h2 id="Remarks">备注</h2>
<p>ImageSearch can be used to detect graphical objects on the screen that either lack text or whose text cannot be easily retrieved. 例如, it can be used to discover the position of picture buttons, icons, web page links, or game objects. Once located, such objects can be clicked via <a href="Click.htm">Click</a>.</p>
<p>A strategy that is sometimes useful is to search for a small clipping from an image rather than the entire image. This can improve reliability in cases where the image as a whole varies, but certain parts within it are always the same. One way to extract a clipping is to:</p>
<ol>
  <li>Press <kbd>Alt</kbd>+<kbd>PrintScreen</kbd> while the image is visible in the active window. This places a screenshot on the clipboard.</li>
  <li>Open an image processing program such as Paint.</li>
  <li>Paste the contents of the clipboard (that is, the screenshot).</li>
  <li>Select a region that does not vary and that is unique to the image.</li>
  <li>Copy and paste that region to a new image document.</li>
  <li>Save it as a small file for use with ImageSearch.</li>
</ol>
<p>To be a match, an image on the screen must be the same size as the one loaded via the <em>ImageFile</em> parameter and its options.</p>
<p>The region to be searched must be visible; in other words, it is not possible to  search a region of a window hidden behind another window. By contrast, images that lie partially beneath the mouse cursor can usually be detected. The exception to this is game cursors, which in most cases will obstruct any images beneath them.</p>
<p>Since the search starts at the top row of the region and moves downward, if there is more than one match, the one closest to the top will be found.</p>
<p>Icons containing a transparent color automatically allow that color to match any color on the screen. Therefore, the color of what lies behind the icon does not matter.</p>
<p>ImageSearch supports 8-bit color screens (256-color) or higher.</p>
<p>The search behavior may vary depending on the display adapter's color depth (especially for GIF and JPG files). Therefore, if a script will run under multiple color depths, it is best to test it on each depth setting. You can use the shades-of-variation option (*n) to help make the behavior consistent across multiple color depths.</p>
<p>If the image on the screen is translucent, ImageSearch will probably fail to find it. To work around this, try the shades-of-variation option (*n) or make the window temporarily opaque via <code><a href="WinSetTransparent.htm">WinSetTransparent</a>("Off")</code>.</p>
<h2 id="Related">相关</h2>
<p><a href="PixelSearch.htm">PixelSearch</a>, <a href="PixelGetColor.htm">PixelGetColor</a>, <a href="CoordMode.htm">CoordMode</a>, <a href="MouseGetPos.htm">MouseGetPos</a></p>
<h2 id="Examples">示例</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a></p>
<pre>ImageSearch FoundX, FoundY, 40, 40, 300, 300, "C:\My Images\test.bmp"</pre>
</div>
<div class="ex" id="ExScreen">
<p><a href="#ExScreen">#2</a></p>
<pre>CoordMode "Pixel"  <em>; Interprets the coordinates below as relative to the screen rather than the active window.</em>
try
{
    if ImageSearch(FoundX, FoundY, 0, 0, A_ScreenWidth, A_ScreenHeight, "*Icon3 " A_ProgramFiles "\SomeApp\SomeApp.exe")
        MsgBox "The icon was found at " FoundX "x" FoundY
    else
        MsgBox "Icon could not be found on the screen."
}
catch exc
    MsgBox "Could not conduct the search due to the following error:`n" exc.Message
</pre>
</div>

</body>
</html>